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About This Manual 


Purpose of this Manual 


This manual describes the programming and use of SQL C-ODBC, which is an 
interface that enables you to use the ODBC API to create applications that connect 
with an SQL Connector Data Source. TheSsQL Connector Data Source is used to 
maintain and manage a reference list of physical databases and tables. These 
database table references are stored in the Data Source, and used by soL C-ODBC to 
connect client applications to these databases. 


This manual provides descriptions and examples that are, as nearly as possible, 
generic for all databases supported by SQL Connector. Unless stated as an exception, 
SQL statements and procedures developed with the material in this document will be 
portable across all databases, regardless of the specific SQL requirements of the 
database. 


Intended Audience 


This document is intended for programmers who will be creating and maintaining 
applications which use SQL C-ODBC to connect to physical databases. It provides 
details on creating and configuring ODBC data sources, summarizes ODBC API usage, 
and provides information on how ODBC functions and SQL grammar map to SQL C- 
ODBC features. 


This document assumes that programmers are familiar with the ODBC Application 
Programming Interface (API). For information about the ODBC API, seethe Microsoft 
ODBC 2.0 Programmer's Reference and SDK Guide 


Structure of this Manual 


This manual consists of chapters which describes how to configure and test SQL C- 
ODBC. 


Associated Documents 


The soL Connector document set contains these manuals: 
* SQL Connector Overview 
* SQL Connector Installation Guide 
* SQL Connector Administration Guide 
。 SQL Connector SQL Grammar Manual 
* SQL Connector ODBC Programmer's Guide 
* SQL Connector J DBC Programmer's Guide 
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Operating System Conventions 


When there are differences in commands, examples, or syntax between operating 
systems, the following abbreviations are used: 


Abbreviation Meaning 
NetWare the Novell NetWare operating system 
Windows the Microsoft Windows 95/98/NT operating systems 
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Overview 





1.1 Introduction 


SQL Connector is a Data Request Broker for database access. It provides the capability 
of using standard Structured Query Language (SQL) to access data in tables in 
different databases. Thetables are cataloged in an SQL Connector Data Source, which 
can then be accessed by client applications using the Open Database Connectivity 
(ODBC) interface. 


The sQL Connector Data Source is created and maintained by the Data Source 
Administrator and documented in the Administration Guide. 


1.2 Architecture 


ODBC dient applications can access the sq. C-DRB (Data Request Broker) from any 
system that supports the ODBC environment. The dient application uses the SQL C- 
ODBC API to connect to SQL C-DRB running on a network server. SQL C- DRB uses 
thesQL Connector Data Source to connect to Oracle on the network server or to remote 
ODBC databases using the SQL Connector ODBC Data Driver. 


1.2.1 ODBC Client Configuration 


An sQL C-ODBC client application uses the following Windows layers to connect tothe 
network server and the database server. 


e Programming Layer 





ODBC Driver Manager odbc32.d11 


e System Layer 
Driver Library tod32.dll, vtx3.dll 
Socket Library wsock32.d11l 


1.2.2 Data Request Broker Configuration 


The system runtime environment uses TCP/IP network sockets to communicate with 
the server. The server executes a program which listens for incoming requests on a 
specified TCP/IP socket. 


e System Layer 
Network Listener vtxnetd.nlm, vtx16.nlm 
e Connection Layer 


SOLC Host sqlcmon.nlm, sqic.nim 
Data Sources local and remote databases 
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The soL Connector network listener runs on the Data Broker system (typically from 
thetime the Data Broker system is booted). Thelistener responds to requests from a 
specified TCP/IP socket. When it receives a network request from the dient, it creates 
a dient thread (if oneis not already created), which then changes the network request 
into a database request and calls the SQL Connector Data Broker engine. The Data 
Broker engine uses the Data Source to access physical databases. 


1.2.3 Database Drivers Configuration 


The soL Connector Data Drivers are used to connect the Data Source to local and 
remote databases. Remote connectivity is discussed in the Administration Guide 


1.3 ODBC Interface 


ODBC (Open Database Connectivity) is an industry-standard API (application 
programming interface) for connecting client applications and data servers. For more 
information about the ODBC API, seethe Microsoft ODBC 2.0 Programmer’s Reference 
and SDK Guide 


The ODBC API documentation specifies the names and arguments of functions which 
define the interface between the client application and the data source. However, 
within the documentation, there are defined levels of conformance to the ODBC 
standard, and there are sections of the standard which allow vendor-defined features 
(for example, datatypes and error messages). 


The purpose of this manual is to discuss the implementation and programming of SQL 
C-ODBC as it relates to the ODBC standard. 


For a discussion of the SQL grammar supported by SQL Connector, see the SQL 
Grammar Manual. 


Installation of saL C-ODBC is discussed in the Installation Guide and creation and 
maintenance of a Data Source is discussed in the Administration Guide The 
remainder of this document assumes that SQL C-ODBC has been successfully 
installed and a Data Source is available for use. 
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Data Source Setup and Connection 





2.1 Introduction 


This chapter discusses creating and configuring an SQL Connector ODBC data source 
name (DSN) on a Windows system. For configuration information on NetWare 
systems, see Appendix G. 


A DSN isa Windows ODBC connection toan SQL Connector Data Request Broker and 
Data Source on a network server. A DSN requires the name of the Data Source and 
the name of the network server that is running the Data Request Broker. Oncethe 
DSN is created, an ODBC application can connect to a SQL Connector Data Source by 
using the DSN. 


2.2 Data Source Setup 


2.2.1 Introduction 


ThesQL C-ODBC installation procedure installs the saL C-ODBC driver and related 
software. See the Installation Guidefor the details. The next step is to create an 
ODBC data source name. 


The ODBC data source setup is controlled by the Microsoft ODBC Driver Manager. 
The Driver Manager displays a series of dialog screens that display the currently 
installed ODBC drivers and that list, create and renove ODBC data sources that are 
connected to those drivers. The data source definitions are stored in the system 


registry. 
When a Windows ODBC application executes, the ODBC Driver Manager calls the sQL 
Connector Driver Library (see “ODBC Client Configuration”). 


2.2.2 Setup 


To access the SQL C-ODBC setup dialog box, do the following: 
1. Fromthe Control Panel, double-click the ODBC icon. 
2. Click on the ODBC Drivers tab. 


3. A list of installed drivers will appear. You can confirm installation of the soL C- 
ODBC driver by the appearance of an entry for the soL Connector Driver in the 
driver list. 
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Microsoft ODBC lar Oracle 2573 3771.00 Microsoft Corporation 
Microsoft Paradox Creer [*.db ] 400371108  Macrosoft Comporetion 
Mictasalt Ted Deer "bd: “esl 400371108 — Manasefl Coiperstan 
Microsoft Visual ForPra Diver 6.00.8428.00 Macrsell Corporation 
Microsoft Visual FoxPro Diver [".dbf] 6.00.6428.00 Microsoft Corporation 
Dracle73 2.05 ü3 01 Oracle Corporalion 


Pervasive Software DIDBC-32 2.50.02 02 Pervasive Software Inc. 
SOL Server 3.70.06. 23 Microsoft Corporation 
SüLCannector Driver 2510.71.01 Novel Inc. 

Sybase SOL Anywhere 5. 5.065.035.1666 Moi marked 








4. Click on theUser DSN tab or System DSN tab (System DSN is recommended). A list 
of currently installed ODBC data sources will be displayed, for example: 


ce Admet ator 


Microsoft Access Drive [* mdb] 
Microsoft Access Drees [* mdb] 

SOL Servei 

INTERSOLY 3,10 3z-BIT SOLSeret 
Microsoft Access Drevet |" måb] 
Dracle?3 


Oracle? 


Sybase SOL Anywhere 5.0 
SOL Server 
SGUGornmector Dirar 
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5. Click on the Add button. 
The Create New Data Source Dialog box will appear: 


) Create New Data Source 


Microzolt ODBC for Oracle 
Micrasalt Paradox Denver [db | 
Miczasolt Text Dives "lut; "esv] 
Micaoxoft Visual FoxPro Durrer 
Microsoft Visual FoxPro Denver [*.dbf] 
Oracle? 3 

Pervasive Saltmare ODBC-32 


2573301100 — 


4,00.3711.08 
4.00. 3711.08 
5.00.8428. 00 
6.00.8428 00 
205.0301 
250.02 02 
3. 70.06. 23 
2 50.71.01 


- 506.03 1666, dl 





6. Click on the row listing the the saL Connector Driver and then click on the Finish 


button. 
ThesQL C-ODBC Setup dialog box will appear: 


SOL Connector ODBC Setup 
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2.2.3 Connection I nformation 


The connection information is as follows: 


Data Source Name 


The Windows name of the ODBC data source, for example, "server1 demo". A 
recommended convention is to indude the Server and Data Source name in the ODBC 
data source name. In this case, the Server name is "server1" and the Data Source 
name is "demo". 

Description 


A description of the data source name. For example "Demo database on Server 1". 


Connection String 
A string for the network connection, which is in the following format: 


/datasource@[port: ]host!service[,switchA[,switchB[,switchC...]]] 





datasource - required 
The name of the SQL Connector Data Source on the network node. 
Sample datasource name: 


demo 


port - required 

A port number used by TCP/IP socket services. This number must match the number 
used when the SQL Connector listener is started on the server. 

host - required 


The name of the network server or internet address (format nnn.nnn.nnn.nnn) which 
is running SQL C-DRB. The name must be in the system hosts file if DNS is not 
enabled.. 





Operating System | Hosts File Name and Location 
Windows NT $SYSTEM_ROOT%\system32\drivers\etc\hosts 














Windows 95/98 SWINDIR%S\hosts 














service - required 
Name of the executable host program on the network server: 


vtx16 


switchA, switchB, switchC... 


SQL Connector switch values or environment variables. For a full description, see the 
SQL Grammar Manual. The format is: namel=valuel 


Example: 


An example of a complete connection string is shown below: 
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/demo81958:serverl!vtx16,S9S TRACE-yes,SMARTTRACE-sql.trc 


Example Notes: 
1. The Data Source is named demo. 
2. TCP/IP port 1958 is used on node server1 
3. The host program is named vt x16. 


There aretwo switches used in this example: 
a. SS TRACE =yes 
This switch turns on database tracing. All activity with local and remote 


databases will be written toa trace file. This trace fileis useful for debugging and 
optimizing database applications. 


b. SMARTTRACE =sql.tre 
This switch names the trace file. If the name is not set, a default name will be 


used. The default name is s<year-day-number><hour-minute>.trc, for example, 
s50411634.trc, and the default directory is the location of the loaded programs. 


Other switch variables are discussed in the SQL Grammar Manual. 


2.3 Connecting to the ODBC Data Source 


When an application connects to SQL Connector using the ODBC function 
SQLDriverConnect, the application may generate a prompt for data source 
information. This prompt is usually in the form of a dialog box. Completethe entries 
as follows: 

e Data Source Name: name of the SQL Connector data source connection 

e Username: «network server username» 


e Password: «network server password 
Note that Username and Password in this context provides network server access. 


2.4 Changing the ODBC Data Source 


Toremove or reconfigure an ODBC data source: 
1. Fromthe Control Panel, double-click the ODBC icon. 
2. Click on the System DSN tab. 


You will see a list of currently installed ODBC data sources. Usethe arrow keys 
to highlight a data source. 


3. Click on the Remove button. 
Choose the Y es button to confirm the deletion. The data source will be deleted. 
4. Click on the Configure button. 


You will then see same dialog box that was used when the data source was created. 
Y ou can change the parameters and press OK or Cancel when finished. 
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2.5 Testing the ODBC Data Source 


2.5.1 


Sample Programs 


TheNetWare PUBLIC directory contains a Samples subdirectory that has two programs 
for testing an SQL C-ODBC Data Source connection on two and threetiers. One 
program (odbcping) verifies the installation by connecting from a client system (first 
tier) to a Data Source on a network server (second tier) and reporting success or 
failure. The other program (odbc join) connects from a dient (first tier) to a Data 
Source on a network server (second tier) and retrieves joined data using a remote 
ODBC Data Driver on a database server (third tier). Both programs are supplied in 
source form (C language) and compiled code (executablefile). The source codeis listed 
in Appendices D and E. 


The following programs can be copied from the Netware PUBLIC directory to a 
Windows client system (i.e., the system that will run the sample programs). The file 
locations are: 


SYS:PUBLI CASQLCNsamplesNwindowsNodbcNodbcjoin.c 
SYS: PUBLIC\SQLC\samples\windows\odbc\odbcjoin.exe 
SYS: PUBLIC\SQLC\samples\windows\odbc\odbcping.c 
SYS: PUBLIC\SQLC\samples\windows\odbc\odbcping.exe 


2.5.2 Sample Data 


Warning: 


2.5.3 


A sample database with sample tables is also supplied. The sample data source is a 
Microsoft Access file that contains tables for departments (dept), jobs (job), employees 
(emp) and salaries (sal). This sample database must be copied to a Windows remote 
system that has the ODBC Data Driver installed. The file location is: 


SYS: PUBLIC\SQLC\samples\windows\access\demo.mdb 


Once the file is copied, the following steps should be performed: 

1. On the database server (third tier), create an ODBC Data Source Name "demo" 
that uses the Microsoft Access ODBC driver and the database file demo . mdb. 

2. On the dient system (first tier). run the Data Source Administrator and create a 
Data Source named "demo" on the network server (second tier) that points to the 
ODBC Access data source "aemo" on the database server (third tier). Seethe 
Administration Guidefor details about this step. 


If the Access database is on a NetWare mounted drive, then the NetWare login 
and the Windows NT login must be the same username. 


The Access database is now available for use with the sample programs. 


Using odbcping to Verify a Connection 


After creating the SQL C-ODBC data source as discussed above, the odbcping 
program can be executed in an MS-DOS command window or a C/C++ development 
environment. ThesQL C-ODBC setup dialog box can have an entry as follows: 


Data Source name: Serverl DEMO 
Description: Connection to Node SERVER1 Data Source DEMO 
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Connection String: /demo@1958:serverl!vtx16 
Then odbcping is used as follows: 


Usage: odbcping "data source name" username password 
Example:  odbcping Serverl_DEMO myuser mypass 





If the ODBC connection is established, this message is displayed: 


Successful Connection 


2.5.4 Using odbcjoin to Retrieve Data 


After a connection has been verified, the sample data may be retrieved using the 
odbc join program. The odbc join program is used as follows: 

Usage: odbcjoin "data source name" username password 

Example:  odbcjoin DEMO myuser mypass 





If the data is successfully retrieved, the following text is displayed: 





























































































































select 
dept.deptno, dept.dname, emp.empno, emp.ename, emp.ssno, emp.jobcls 
from 
dept, emp 
where 
dept.deptno = emp.deptno and dept.deptno « 3 
Dept.Deptno Dept.Dname  Emp.Empno  Emp.Ename Emp.SSNO Emp.JobCls 
MARKETING 20265 BASINGER R 394-90-3583 2 
MARKETING 20337 GILBREATH R 553-40-5418 5 
MARKETING 20365 MILLER R 248-95-1471 6 
MARKETING 32024 GOVE T 742-35-6859 4 
MARKETING 33297 ELLISON W 252-60-1283 2 
MARKETING 33733 BANFIELD_S 688-21-4136 4 
MARKETING 33771 NASER_K 848-17-0910 8 
MARKETING 34410 MCCORRY K 015-84-9007 7 
MARKETING 35844 MCCARTNEY H 211-02-7599 7 
MARKETING 35909 LACY C 494-12-0675 7 
MARKETING 38342 KINGSLEY S 107-42-3232 5 
MARKETING 39748 BARNETT N 179-22-5607 4 
MARKETING 63297 ELLISON V 152-60-1283 1 
MARKETING 63647 HAWTHORNE A 735-64-9259 3 
MARKETING 63910 BRANNEN P 355-08-2564 3 
MARKETING 64689 FULFORD W 546-61-8895 5 
MARKETING 67528 BLOCK F 084-40-0022 3 
MARKETING 68355 SWIFT E 358-51-5799 9 
2 TRAINING 20384 KNAPP L 381-26-6148 3 
2 TRAINING 31028 ROCHE D 671-74-2192 9 
2 TRAINING 32482 NICHOLL F 129-79-0929 8 
2 TRAINING 34948 ELLINGTON A 686-40-9928 4 
2 TRAINING 35038 ROMANN H 079-54-8297 9 
2 TRAINING 39208 ELDER N 460-95-5451 2 
2 TRAINING 64948 ELLINGTON Z 586-40-9928 3 
2 TRAINING 68551 HOLMES P 664-23-5820 3 
2 TRAINING 69208 ELDER M 360-95-5451 1 
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ODBC Implementation 


I ntroduction 


The ODBC standard specifies a minimum level of functionality that must be provided 
by an ODBC driver in order to connect to ODBC applications. This minimum level 
applies to a set of callable functions, a subset of SQL grammar rules, and a set of 
datatypes. The ODBC standard also allows vendors to provide additional levels of 
support, additional functionality, datatypes, etc. 


Thereis a set of ODBC functions that allow an ODBC application to discover the 
functionality available from an ODBC driver. The ODBC application then knows the 
limits of the driver and does not try to exceed the limits. 


This chapter documents the functionality availablein the SQL C-ODBC driver, as an 
aid to programmers during application development. TheMicrosoft ODBC 2.0 
Programmer's Reference and SDK Guide provides the reference for the information in 
this chapter. 


3.2 Compliance Level 


SQL C- ODBC supports all of the following ODBC functions: 











































































































Core Functions Level 1Functions Level 2Functions 
SOLAllocConnect SOLBindParameter SOLBrowseConnect 
SOLAllocEnv SQLColumns SQLDataSources 
SOLAllocStmt SOLDriverConnect SOLExtendedFetch 
SOLBindCol SQLDrivers SQLNumParams 
SQLCancel SQLGetConnectOption SOLPrimaryKeys 
SOLColAttributes SQLGetData 

SQLConnect SOLGetFunctions 

SOLDescribeCol SOLGetInfo 

SOLDisconnect SQLGetStmtOption 

SQLError SOLGetTypeInfo 

SOLExecDirect SOLParamData 

SOLExecute SQLSetConnectOption 

SOLFetch SOLSetStmtOption 

SOLFreeConnect SQLSpecialColumns 

SOLFreeEnv SQLStatistics 

SOLFreeStmt SOLTables 

SQL GetCursorN ame 
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Core Functions Level 1 Functions Level 2 Functions 
SQLNumResultCols 
SQLPrepare 
SQLRowCount 
SQLSetCursorName 
SQLSetParam 
SQLTransact 






































3.3 SQL Grammar 


SQL Connector supports most all of the elements in the minimum SQL grammar, and 
some elements of the core and extended SQL grammar. For a complete discussion of 
SQL grammar elements, see Appendix C in the Microsoft ODBC 2.0 Programmer's 
Referenceand SDK Guide 


Core elements not supported are Data Definition Language (DDL) statements (cREATE 
and DROP TABLE, CREATE and DROP INDEX). SQL Connector uses database table and 
column information that is imported from existing physical databases. Tables and 
indexes are first created in the physical database using the appropriate database tools, 
then imported into SQL Connector. 














The SQL Grammar elements are categorized as follows: 
1. Minimum SQL grammar elements: 


* Data Manipulation Language (DML): simple SELECT, INSERT, UPDATE and 
DELETE 


e Expressions: simple, such asa > B + c 
e Datatype: CHAR 
2. Core SQL grammar elements: 
* Minimum SQL grammar and data types 
e DML: full sELECT 
e Expressions: subquery and aggregates such as sum and MIN 
e Datatypes: DECIMAL, SMALLINT, FLOAT, REAL, DOUBLE 
3. Extended SQL grammar 
e Minimum and Core SQL grammar and data types 


e Expressions: scalar functions such as suBsTRING and date, time, and 
timestamp literals 


e Datatypes: DATE, TIME, TIMESTAMP 




































































3.4 SQL Datatypes 
The soL Connector ODBC Driver supports the following SQL datatypes: 
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SQL Connector | SQL Maximum Case 
Datatype Datatype Column Size | Nullable | Sensitive | Searchable 
char SQL_CHAR 255 Y Y Y 
decimal SQL_NUMERIC 19 Y N Y 
integer SOL INTEGER 10 Y N Y 
smallint SOL SMALLINT 5 x N X 
float SOL FLOAT 19 Y N Y 
real SQL REAL 19 Y N Y 
double SQL_DOUBLE 19 Y N Y 
date SQL_DAT IME 10 Y N Y 
time SQL TIME 8 Y N Y 
timestamp SOL TIMESTAMP 19 Y N Y 
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Driver and Connection Attributes 


Thefollowing table lists the information type and values that are returned by 


SQLGetInfo when connected to an SQL Connector data source. See the discussion of 
SQLGetInfo in the Microsoft ODBC 2.0 Programmer's Reference and SDK Guide 








Information Type 


Information Value 








Driver I nformation 































































































































































































































































































SQL ACTIVE CONNECTIONS 8 
SOL ACTIVE STATEMENTS 256 
SOL DATA SOURCE NAME <ODBC Data Source Name» 
SQL DRIVER, NAME tod32.dll 
SQL DRIVER, ODBC, VER 02.50 
SQL DRIVER, VER 02.50.1064 
SQL FETCH DIRECTION SQL FD, FETCH NEXT 
SQL FILE USAGE SOL FILE NOT SUPPORTED 
SQL GETDATA, EXTENSIONS SQL GD ANY COLUMN 
SQL GD GET ANYORDER 
SQL GD BOUND 

SQL LOCK TYPES ***** «not set» ***** 
SQL ODBC, API CONFORMANCE SQL OAC, LEVEL1 
SQL ODBC, SAG CLI CONFORMANCE SQL OSCC NOT COMPLIANT 
SQL ODBC VER 03.00.0000 
SQL POS OPERATIONS ***** «not set» ***** 
SQL ROW UPDATES N 
SQL SEARCH PATTERN ESCAPE N 
SQL SERVER NAME ODBXHOST 

DBMS Product | nformati on 
SQL DATABASE NAME 
SOL DBMS NAME SOL Connector 
SQL DBMS. VER 03.01.0000 

Data Source Information 
SQL ACCESSIBLE PROCEDURES N 
SQL ACCESSIBLE TABLES Y 





L BOOKMARK PERSISTENCE 


大 大 大 大 大 «not set» 大 大 大 大 大 





L CONCAT NULL BEHAVIOR 














SOL CB NON NULL 





L CURSOR COMMIT BEHAVIOR 














SOL CB PRESERVE 




















L CURSOR ROLLBACK BEHAVIOR 








SOL CB PRESERVE 

















L DATA SOURCE READ ONLY 
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Information Type 


Information Value 











SOL DEFAULT TXN ISOLATION 


SOL TXN REPEATABLE READ 















































































































































SQL MULT RESULT SETS N 

SOL MULTIPLE ACTIVE TXN Y 

SOL NEED LONG DATA LEN B 

SOL NULL COLLATION SOL NC HIGH 

SOL OWNER TERM schema 

SQL PROCEDURE TERM procedure 

SOL QUALIFIER TERM Schema 

SQL SCROLL CONCURRENCY ***** «not set» ***** 
SQL SCROLL OPTIONS SOL SO FORWARD ONLY 

















SOL STATIC SENSITIVITY 


***** «not set» ***** 






































SOL TABLE TERM table 
SQL TXN CAPABLE SOL TC ALL 
SQL TXN ISOLATION OPTION SQL TXN READ UNCOMMITTED 





























SOL USER NAME 








«username» 





Supported SQL 








SQL ALTER TABLE 





***** «not set» ***** 



























































SQL COLUMN ALIAS N 

SQL CORRELATION NAME SOL CN ANY 

SQL EXPRESSIONS IN ORDERBY Y. 

SQL_GROUP_BY SOL GB GROUP BY CONTAINS SELECT 
SOL IDENTIFIER CASE SOL IC LOWER 
































SOL IDENTIFIER QUOTE CHAR 














SOL KEYWORDS 





«See Appendix B» 








































































































SQL LIKE ESCAPE CLAUSE Y 
SQL NON NULLABLE COLUMNS SQL NNC NON NULL 
SQL ODBC SQL CONFORMANCE SQL OSC EXTENDED 
SQL ODBC SQL OPT IEF N 
SQL ORDER BY COLUMNS IN SELECT Y 
SQL OUTER JOINS Y 








(2.01) SOL OJ CAPABILITI 





E 
n 


***** «not set» ***** 


































































































































































































SOL OWNER USAGE SQL OU DML STATEMENTS 
SQL OU TABLE DEFIITION 
SOL OU INDEX DEFINITION 

SQL POSITIONED STATEMENTS KAAKE ANON SCE AAS AK 

SQL_PROCEDURES N 

SOL QUALIFIER LOCATION SOL OL START 

SOL QUALIFIER NAME SEPARATOR 

SOL QUALIFIER USAGE SOL QU DML STATEMENTS 
SOL QU TABLE DEFINITION 
SOL QU INDEX DEFINITION 
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Information Type 


Information Value 
















































































SQL QUOTED IDENTIFIER CASE SOL IC LOWER 
SQL SPECIAL CHARACTERS HSE 
SQL SUBQUERIES SQL SQ EXISTS 
SQL SQ IN 
SQL SQ CORRELATED SUBQUERIES 


























SQL 


UNION 


***** «not set» ***** 





SQL Limits 





SQL | 





[AX BINARY LITERAL LEN 








SOL 





[AX CHAR LIT 





F 








SOL 


MAX COLUMN 














H 





SOL MAX COLUMNS IN 





SOL 


[AX COLUMNS, IN 





SOL 


[AX COLUMNS, IN 





SOL MAX COLUMNS IN 











SOL MAX COLUMNS IN 























SQL 





[AX CURSOR NAI 























SOL 





[AX INDEX SIZ 








SOL 














MAX OWNER NAM 




















SOL MAX PROCEDU 














SQL | 








[AX QUALIFI 








ER NAME LEN 














SOL 


[AX ROW SIZI 


O|o|oj|o|o|ojoj|o|lo|o|ojo!o!o 





SOL 


MAX ROW SIZI 





INCLUDES LONG 














SOL MAX STATEM 








ENT LEN 








SOL 








[AX TABLE 














SQL 


























SQL 
































Scalar Function Information 





SQL CONVERT FUNC 








IONS 


大 大 大 大 大 


«not 


set» 


大 大 大 大 大 





SQL NUMERIC FUNC 

















IONS 


SQL FN NUM ABS 





SQL FN | 


NUM 


| MOD 

















SOL STRING FUNCTIONS 


SOL FN. 


STR 


CONCAT 





SOL FN. 


STR 


SUBSTRING 





SOL FN. 





STR 


CHAR 





SQL SYSTEM FUNCTIONS 











SOL FN. 


SYS_ 


IFNULL 








SQL_TIMEDATE_ADD_INTERVALS 








T 


大 大 大 大 大 


«not 


set» 


大 大 大 大 大 











SQL TIMEDATE DIFF INTERVALS 








大 大 大 大 大 


«not 


set» 


大 大 大 大 大 





SOL TIMEDATE FUNC 




















IONS 


大 大 大 大 大 


«not 


set» 


大 大 大 大 大 





Conversion Information 





SQL | 





CONVERT BIGIN 








大 大 大 大 大 


«not 


set» 


大 大 大 大 大 





SQL | 





CONVERT BINARY 





大 大 大 大 大 


«not 


set» 


大 大 大 大 大 











SQL | 

















CONVERT BIT 








大 大 大 大 大 





«not 





set» 


大 大 大 大 大 
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Information Type Information Value 

SQL CONVERT CHAR Xue not set» FEA 
SQL CONVERT DATE Aw net get **årA 
SQL CONVERT DECIMAL **£t** «not set» ***** 
SQL CONVERT. DOUBLE ex 0 sebo ras 
SQL CONVERT FLOA KR «not sets TEKER 
SQL CONVERT INTEGER mk uuo sep> RW 
SQL CONVERT LONGVARBINARY FABER «not. set *++*** 
SQL CONVERT LONGVARCHAR ***** «not set» ***** 
SQL CONVERT NUMERIC ***** «not set» ***** 
SOL CONVERT. REAL KK snot SCS: FER EK 
SQL CONVERT SMALLINT ***** «not get» SKAER 
SQL CONVERT TIME kat «Not set EEA 
SQL CONVERT TIMESTAMP Aw*** not sepe **åtrA 
SQL CONVERT TINYINT BOR CHOP gate ***+*$ 
SQL CONVERT VARBINARY RAEKE «not set **w*w 
SQL CONVERT VARCHAR ***** «not get» **w** 
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SQL Keywords 


The following keywords are reserved for use by SQL Connector. If thereis existing SQL 
metadata (tables and columns) that already usethese keywords, then references tothe 
metadata must be surrounded by double quotes. If new metadata (tables and columns) 
is created, then the metadata should not use words in this list. 














































































































abort att name audit average bcd bcdfixed 
bcdflt binary bottom breakable call carrycolumns 
center checkpoint columnno committed concat copyin 
copyout cumulative currentdate currentmoment |currenttime database 
databasename |datatype days daytime dba detail 
detailno editstring elseif enddo endif endpage 
endsection endstore endstream errorlimit exclusive exit 
fetchnumber fieldcomment fieldinfo fieldlabel filestatus fixed 
float4 float8 footsize format forms function 
getdate gettime giving groupcount groupno guide 
head header headformat heading highlighting |host 
hostfield hostparameter |hours ifnull index initpage 
initsection inout inquire intl int2 int4 
ints isnull killdbin leave leftmargin lineno 
lowercase maximum message midnight minimum minlocks 
minutes months need none nvl oddpage 
outerjoin overwriting page pagebottom pagelength pageno 
pagetop paging panelwidth parameter presorted print 
comment 
prompt prompting protected reconfigure recordno recordtype 
recover rel id rel name repeatable report reportbottom 
reporttop reserving return returns rightmargin savepoint 
seconds sectionno segmentsize Separation serializable |shared 
show Skip skipping space spacing spreading 
start startpage startsection |status stddev store 
stream sync synonym to_char to_date to_number 
today top total truncate unbreakable uncommitted 
unsafe unset uppercase userid variance vaxday 
vaxhour vaxmidnight vaxminute vaxsecond vaxtime verify 
week weeks while width years 
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C 
E-—————————————————————————————À— = 
ODBC Errors 


When an error occurs, the soL C- ODBC driver returns the native error number, the 
SQLSTATE (an ODBC error code), and an error message. ThesQL C-ODBC driver 
gets this information from errors that are detected by the driver itself and from errors 
that are returned by SQL C-DRB. 


For errors that occur within the Data Source or from data sources connected to the 
Data Source, thesQL C-ODBC driver returns thenative error number that is returned 
by SQL C- DRB, and the message identification and the message text. For a list of 
native error numbers, see the table sqimsg in the Data Source named msgdb. This 
table has four columns: 





msgnum integer not null 
facility char (8) not null 
msgid char (26) not null 
msgtxt char (160) not null 


The message number, message identification and messagetext arethe first, third and 
fourth columns. 


Error Message Syntax 

Error messages havethe following format: 

SQLSTATE native error [vendor] [ODBC component] [data source] error message 
The error message returned by SQL C-DRB is the concatenation of the message 
identification and the message text. There may be morethan one error line returned. 
Example Error Messages 


If the ODBC data source is not found: 


IMOO2 0 [Microsoft] [ODBC Driver Manager] Data source name not found 
and no default driver specified 


If the Data Source is not found: 


S1000 -1 [TOD] [ODBC Driver] [Net] $ROP-E-DICPARSE, 
Can't Parse Dictionary File Name '../examples/xxx' 
SRMS-E-FNF, file not found 








If atablein the Data Source is not found: 


51000 -23457819 [TOD] [ODBC] [SQLI] $ROP-E-TABUND, 
Table emp Undefined in Dictionary File ../examples/demo 
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D 
E-———————— ————— — ——— — — — ÜÀ Q1 
ODBCPI NG Source Code 


// ODBC Ping Test 





#include «windows.h» 
#include <stdio.h> 
#include <sqlext.h> 


void* checkError (SQLHENV envHandle, SQLHDBC dbcHandle, 
SQLHSTM stmtHandle, SQLRETURN retCode, char* retmsg) ; 








// 
main (int argc, char *argv[]) 
{ 
SQLRETURN rc; 
SOLHENV henv; 
SOLHDBC hdbc; 
SQLCHAR dsn[63]; 
SQLCHAR uid[63]; 
SQLCHAR pwd[63]; 
char msg[255]; 
// arg[0]= executable name, arg[1] = dsn, arg[2] = uid, arg[3] = pwd 
if (argc < 3) { 
printf ("Usage: odbcping \"data source namel" username password Nn"); 
goto finish; 


} 








strcpy ((char*)dsn, argv[1]); 
strcpy ((char*)uid, argv[2]); 
strcpy ((char*)pwd, argv[3]); 
printf ("\nConnecting to ODBC Data Source, dsn-$s, uid-$s, pwd=%s\n", 
dsn, uid, pwd); 
rc = SQLAllocEnv(&henv); 
checkError (SQL NULL HENV, SQL NULL HDBC, SQL NULL HSTMT, rc, msg); 
if (rc == SQL SUCCESS) { 
rc = SQLAllocConnect (henv, é&hdbc); 
checkError (henv, SQL NULL HDBC, SQL NULL HSTMT, rc, msg); 
if (rc == SQL SUCCESS) { 
rc = SQLConnect (hdbc, dsn, SQL NTS, uid, SQL NTS, pwd, SQL NTS); 
checkError (henv, hdbc, SQL NULL HSTMT, rc, msg); 
if (rc == SQL SUCCESS) 
printf ("\nSuccessful Connection Wn"); 























rc = SQLDisconnect (hdbc); 
rc = SQLFreeConnect (hdbc); 
rc = SQLFreeEnv (henv); 
finish: 

return 0; 
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Tp 


void* checkError 






































(SQLHI 

















ENV envHandle, 
SOLHSTMT stmtHandle, 


SOLHDBC dbcHandle, 
SQLRETURN retCode, 





char* retmsg) 








SOLRETURN krc; 
SOLCHAR sqlState[5]; 
SQLINTEGER sqlNativeError; 
SQLCHAR msg[255]; 
SOLSMALLINT lmsg; 
strcpy ((char*)retmsg, "[SQL SUCCESS]"); 
if (retCode != SQL SUCCESS) { 
krc = SQLError (envHandle, dbcHandle, stmtHandle, sqlState, 
&sglNativeError, msg, sizeof(msg), &lmsg); 
while (kre != SQL NO DATA FOUND) { 
sprintf (retmsg, "%s $5i $s", sqlState, sqlNativeError, msg); 
printf ("%Ss\n", retmsg); 
krc = SQLError (envHandle, dbcHandle, stmtHandle, sqlState, 
&sqlNativeError, msg, sizeof(msg), &lmsg); 


} 


return 0; 
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ODBCJ OI N Source Code 


// ODBC Join Test 


#include «windows.h» 
#include <stdio.h> 
#include <sqlext.h> 
































void* checkError (SQLHENV envHandle, SQLHDBC dbcHandle, 
SOLHSTMT stmtHandle, SQLRETURN returnCode, char* retmsg); 
char* getData (SOLHENV envHandle, SQLHDBC dbcHandle, 
SQLHSTMT stmtHandle, SQLUSMALLINT colNo, int outLen); 
/ / 
main (int argc, char *argv[]) 
{ 
SOLRETURN rc; 
SOLHENV henv; 
SOLHDBC hdboe; 
SOLHSTMT hstmt; 
char dsn[31]; 
char uxd[31]s$ 
char pwd[31]; 
char msg[255]; 
// arg[0]= executable name, arg[1] = dsn, arg[2] = uid, arg[3] = pwd 
if (argc < 4) 
printf ("\nUsage: odbcjoin "data source name" username password\n"); 


Goto error; 

} 
strcpy 
strcpy 
strcpy 


( (char*)dsn, 
( (char*)uid, 
( (char*)pwd, 


argv[1]); 
argv[2]); 
argv[3]); 


/ / 
// 


Allocate environment, 
connect to database 
= SQLAllocEnv (&henv); 
= SQLAllocConnect (henv, 
= SQLConnect (hdbc, 
SQL_NTS, 
checkError (henv, hdbc, 
if (rc != SQL SUCCESS) 
rc = SQLAllocStmt (hdbc, 





printf ("\nselect\n") ; 
printf (" dept.deptno, 
emp.ssno, 
printf ("from\n"); 
printf (" dept, emp\n"); 
printf ("where\n"); 
printf (" dept.deptno = 





(SOLCHAR*) pwd, 
SQL_NULL_HSTMT, 

goto error; 
&hstmt); 


dept.dname, 
emp.jobcls\n"); 


connection and statement handles 


&hdbc) ; 
(SQLCHAR*) dsn, 


SQL_NTS, 
SOL NTS); 


(SOLCHAR*) uid, 


rc, msg); 


emp.empno, emp.ename, 


emp.deptno and dept.deptno < 3\n\n"); 
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printf ("Dept.Deptno Dept.Dname  Emp.Empno  Emp.Ename Emp.SSNO 
Emp.JobCls Nn"); 
printf (" Nn"); 
rc = SQLExecDirect (hstmt, (SOLCHAR*)"select d.deptno, d.dname, 
e.empno, e.ename, e.ssno, e.jobcls from dept d, emp e where 
dept.deptno = emp.deptno and dept.deptno « 3", SQL NTS); 
checkError (henv, hdbc, hstmt, rc, msg); 
if (rc != SQL SUCCESS) goto finish; 
rc = SQLFetch (hstmt); 
checkError (henv, hdbc, hstmt, rc, msg); 
if (rc != SQL SUCCESS) goto finish; 
while (rc != SQL NO DATA FOUND) { 
strcpy (msg, " "ys 
strcat (msg, getData (henv, hdbc, hstmt, 1, 8)); 
strcat (msg, getData (henv, hdbc, hstmt, 2, 13)); 
strcat (msg, getData (henv, hdbc, hstmt, 3, 10)); 
strcat (msg, getData (henv, hdbc, hstmt, 4, 15)); 
strcat (msg, getData (henv, hdbc, hstmt, 5, 16)); 
strcat (msg, getData (henv, hdbc, hstmt, 6, 7)); 
printf ("%Ss\n",msqg) ; 
re = SQLFetch (hstmt); 
checkError (henv, hdbc, hstmt, rc, msg); 
} 
printf (" \n"); 
finish: 
rc = SQLFreeStmt (hstmt, SQL DROP); 
rc = SQLDisconnect (hdbc); 
rc = SQLFreeConnect (hdbc); 
rc = SQLFreeEnv (henv); 
error: 


return 0; 





/ / 
void* checkError (SQLHENV envHandle, 


SOLHSTMT stmtHandle, 





SOLHDBC dbcHandle, 









































SQLRETURN returnCode, 


char* retmsg) 


SOLRETURN lrc; 
SQLCHAR sqlState[5]; 
SQLINTEGER sqlNativeError; 
SQLCHAR msg[255]; 
SOLSMALLINT lmsg; 
strcpy ((char*)retmsg, "[SQL SUCCESS]"); 
if (returnCode != SQL SUCCESS) { 
lrc = SQLError (envHandle, dbcHandle, stmtHandle, sqlState, 
&sqlNativeError, msg, sizeof(msg), &lmsg); 
while (lrc != SQL NO DATA FOUND) { 
sprintf (retmsg, "%s $5i $s", sqlState, sqlNativeError, msg); 
printf ("%Ss\n", retmsg); 
lrc = SQLError (envHandle, dbcHandle, stmtHandle, sqlState, 





&sqlNativeError, msg, sizeof(msg), 


} 
return NULL; 


&lmsg) ; 
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/ / 
char* getData (SOLHENV envHandle, SQLHDBC dbcHandle, 
SOLHSTMT stmtHandle, SQLUSMALLINT colNo, int outLen) 














SQLRETURN Ire; 

SQLINTEGER ind; 

static char val[255], msg[255]; 
int Jd 


























lrc = SQLGetData (stmtHandle, colNo, SQL CHAR, (SQLCHAR*)val, sizeof 
val, &ind); 
checkError (envHandle, dbcHandle, stmtHandle, lrc, msg); 





if (ind == SQL NULL DATA) { 
strcpy (val,"~"); 
ind = 1; 


} 

for (i=ind; i<outLen; i++) { 
streat (val, " "js 
} 

return val; 


} 
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FE 


Programming Notes 





F.1 SQL Data Types 


F.1.1 SQL Double Datatype Restriction 


The maximum value of an SQL Doubledatatypeis 1.0e«126. TheSQL-92 documented 
maximum value iS 1.797693134862316e+308. 


F.2 SQL Functions 


F.2.1 SQLBindParameter Restriction 


SQL BindParameter is used to bind a program variable and its null value indicator to 
a parameter in an SQL statement. The null valueindicator must be set before the 
SQL BindParameter is called. 
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G 


ODBC NetWare Client Driver 





G.1 Introduction 


The soL Connector ODBC dient driver is also available as a NetWare NLM. The 
characteristics and behavior of the NetWare version of the driver are identical to the 
Windows version of the driver. TheNetWare ODBC Client Driver can be accessed by 
NetWare applications which call ODBC API functions, such as Web Servers. The 
NetWare ODBC Client Driver uses the NetWare Data Request Broker and Data 
Source to gain access to local and remote databases. The Data Source is created and 
maintained by the Data Source Administrator and documented in the Administration 
Guide There are also two test programs (odbcping and odbc join) that are distributed 
as NLMs. 


G.2 Architecture 


NetWare ODBC client applications can access the SQL C-DRB (Data Request Broker) 
from the same system that supports the NetWare ODBC Client. The dient application 
uses the ODBC API (see Section 1.3) to connect to SQL C-DRB running on a network 
server. SQL C-DRB uses the Data Source to connect to Oracle on the network server 
or to remote databases using the SQL Connector ODBC Data Driver. 


G.2.1 NetWare ODBC Client Configuration 


Ansat C-ODBC dient application uses the following NetWare layers to connect tothe 
network server and the database server. 


e Programming Layer 


ODBC Driver: sqlcodbc.nlm 
Connection Driver: vtxodbc.nlm 
Environment Variables: vtxenv.nlm 


e TheNetWare ODBC Client Driver is loaded using: 


load sqlcodbc 


G.2.2 Data Request Broker Server Configuration 


The ODBC driver directly connects to the SQL Connector Data Request Broker. 
e Connection Layer 


SQLC Host: module sqlcmon.nlm, sqlc.nim 
Data Source: local and remote databases 
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G.3 


I nstallation 


The NetWare ODBC client driver is automatically installed when NetWareis 
installed. No additional steps are necessary. 


G.4 Data Source Setup 


G.4.1 


Warning: 


Data Source Names 


On Windows systems, the ODBC data sources are controlled by the Microsoft OBDC 
Driver Manager. The Driver Manager displays a series of dialog screens that display 
the currently installed OBDC drivers and that list, create and remove OBDC data 
sources that are connected to those drivers. The data source definitions are stored in 
the system registry. 


On NetWare systems, the ODBC data sources are controlled by the Data Source 
Administrator. The Data Source Administrator has a series of web pages the display 
the current Data Sources and that create and remove Data Sources and list tables in 
Data Sources. For further information, see the Administration Guide 


Data Sources names are unique on each Netware server. If a Data Sources name 
already exists when any user creates a new Data Source with the same name 
using the Data Source Administrator, an error will occur, and the Data Source will 
not be created. 


G.4.2 ODBC Trace Files 


ODBC tracing can be started by setting the environment variable odbc trace = y. 
When tracing is on, files are created in sys: \ with names like opBc9999.LoG, where 
9999 is a portion of the SQL Connector thread id. 


The environment variable is set by loading the ODBC environment NL M as follows: 
load vtxenv odbc_trace=y 


G.5 Testing the ODBC Data Source 


G.5.1 Sample Programs 


The NetWare PUBLIC directory contains a Samples subdirectory that has two NLM 
programs for testing an SQL C-ODBC Data Source using one and twotiers. One 
program (odbcping) verifies the installation by connecting to a Data Source on the 
NetWare server (first tier) and reporting success or failure. The other program 

(odbc join) connects to a Data Source on the NetWare server (first tier) and retrieves 
joined data using a remote ODBC Data Driver on a database server (second tier). Both 
programs are supplied in source form (C language) and compiled code (Netware 
loadable module). The source code is listed in Appendices D and E. 


Thefollowing programs can be copied from the Netware PUBLIC directory to any 
NetWare directory that is in the Search Path. The file locations are: 
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SYS: PUBLIC\SQLC\samples\netware\odbc\odbcjoin.c 
SYS: PUBLIC\SQLC\samples\netware\odbc\odbcjoin.nlm 
SYS: PUBLIC\SQLC\samples\netware\odbc\odbcping.c 
SYS: PUBLIC\SQLC\samples\netware\odbc\odbcping.nlm 


G.5.2 Sample Data 


A sample database with sample tables is also supplied. The sample data source is a 
Microsoft Access file that contains tables for departments (dept), jobs (job), employees 
(emp) and salaries (sal). This sample database must be copied to a Windows remote 
system that has the ODBC Data Driver installed. The file location is: 


SYS:PUBLICASQLCNsamplesNwindowsNaccessNdemo .mdb 


Oncethe fileis copied, the following steps should be performed: 


1. On the database server, create an ODBC Data Source Name "demo" that uses the 
Microsoft Access ODBC driver and the database file demo . mab. 


2. RuntheData Source Administrator and createa Data Source named "demo" on the 
network server that points tothe ODBC Access data source "demo" on the database 
server. Seethe Administration Guidefor details about this step. 


Warning: If the Access database is on a NetWare mounted drive, then the NetWare login 
and the Windows NT login must be the same username. 


The Access database is now available for use with the sample programs. 


G.5.3 Using odbcping to Verify a Connection 


After creating the Data Source as discussed above, the odbcping program can be 
executed from the NetWare console (since it has been copied to a directory in the 
search path). The odbcping program is used as follows: 


Usage: odbcping "Data Source" username password 
Example:  odbcping demo myuser mypass 





If the ODBC connection is established, this message is displayed: 


Successful Connection 


G.5.4 Using odbcjoin to Retrieve Data 


After a connection has been verified, the sample data may be retrieved using the 
odbcjoin program (since it has been copied to a directory in the search path). The 
odbcjoin program is used as follows: 


Usage: odbcjoin "Data Source" username password 
Example:  odbcjoin demo myuser mypass 





If the data is successfully retrieved, the following text is displayed: 





select 

dept.deptno, dept.dname, emp.empno, emp.ename, emp.ssno, emp.jobcls 
from 

dept, emp 
where 


dept.deptno = emp.deptno and dept.deptno « 3 
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Dept.Deptno Dept.Dname  Emp.Empno  Emp.Ename Emp.SSNO Emp.JobCls 
MARKETING 20265 BASINGER R 394-90-3583 2 
MARKETING 20337 GILBREATH R 553-40-5418 5 
MARKETING 20365 MILLER R 248-95-1471 6 
MARKETING 32024 GOVE T 742-35-6859 4 
MARKETING 33297 ELLISON W 252-60-1283 2 
MARKETING 33733 BANFIELD S 688-21-4136 4 
MARKETING 33771 NASER K 848-17-0910 8 
MARKETING 34410 MCCORRY K 015-84-9007 7 
MARKETING 35844 MCCARTNEY H 211-02-7599 7 
MARKETING 35909 LACY C 494-12-0675 7 
MARKETING 38342 KINGSLEY S 107-42-3232 5 
MARKETING 39748 BARNETT N 179-22-5607 4 
MARKETING 63297 ELLISON V 152-60-1283 1 
MARKETING 63647 HAWTHORNE_A 735-64-9259 3 
MARKETING 63910 BRANNEN_P 355-08-2564 3 
MARKETING 64689 FULFORD_W 546-61-8895 5 
MARKETING 67528 BLOCK_F 084-40-0022 3 
MARKETING 68355 SWIFT E 358-51-5799 9 

2 TRAINING 20384 KNAPP L 381-26-6148 3 
2 TRAINING 31028 ROCHE D 671-74-2192 9 
2 TRAINING 32482 NICHOLL F 129-79-0929 8 
2 TRAINING 34948 ELLINGTON_A 686-40-9928 4 
2 TRAINING 35038 ROMANN H 079-54-8297 9 
2 TRAINING 39208 ELDER_N 460-95-5451 2 
2 TRAINING 64948 ELLINGTON Z 586-40-9928 3 
2 TRAINING 68551 HOLMES P 664-23-5820 3 
2 TRAINING 69208 ELDER M 360-95-5451 J 















































